Loyalty Management POS API Powered by MuleSoft

Use Loyalty Management Retail and E-commerce POS Integrations API to securely interact with a point of sale (POS) system. This workflow explains the flow of the Loyalty Management POS API:

Enroll a member to the loyalty program

Enrolls a member to Loyalty Program

POST /members

Request

Headers

Authorization

String [Required]

Access token, which is used to make requests to secure resources.

Body

Media type: application/json

member-enrollment-request:

{
  "enrollmentDate": "2023-11-29T10:20:34",
  "membershipNumber": "1100876",
  "associatedContactDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@gmail.com",
    "allowDuplicateRecords": "false",
    "additionalContactFieldValues": {
      "attributes": {
        "PersonMailingCity": "LA"
      }
    }
  },
  "memberStatus": "Active",
  "createTransactionJournals": "true",
  "transactionJournalStatementFrequency": "Monthly",
  "transactionJournalStatementMethod": "Mail",
  "enrollmentChannel": "POS",
  "canReceivePromotions": "true",
  "canReceivePartnerPromotions": "true",
  "additionalMemberFieldValues": {
    "attributes": {
    }
  }
}

Response

member-enrolment-response:

{
    "contactId": "0031Q00002j7f7q",
    "loyaltyProgramMemberId": "0lM1Q0000008SCZ",
    "loyaltyProgramName": "NTO Insider",
    "membershipNumber": "1100876",
    "transactionJournals": [
        {
            "activityDate": "2023-11-29T18:20:34.000Z",
            "journalSubType": "Member Enrollment",
            "journalType": "Accrual",
            "loyaltyProgram": "NTO Insider",
            "loyaltyProgramMember": "1100876",
            "referredMember": null,
            "status": "Processed",
            "transactionJournalId": "0lV1Q0000008jwi"
        }
    ]
}

Retrieve member details

Retrieves member details based on the membershipNumber, membershipId, or posMemId properties.

GET /members

Request

Query Parameters

membershipNumber

String

Specifies the membership number of the loyalty program member.

memberId

String

Specifies the ID of the loyalty program member.

posMemId

String

Specifies the ID of the member in the Point of Sale (POS).

Headers

Authorization

String [Required]

Access token, which is used to make requests to secure resources.

Response

retrieve-member-profile-details-response

{
  "additionalLoyaltyProgramMemberFields": {
    "posMemId__c": "675424",
    "City__c": null,
    "Age__c": null,
    "Anniversary__c": null,
    "posName__c": "TestPOSName",
    "DateOfBirth__c": null,
    "posOrderCount__c": 10,
    "Gender__c": null,
    "SeedData__c": false,
    "posMemMobile__c": "1234567890"
  },
  "associatedAccount": null,
  "associatedContact": {
    "contactId": "003Dn00000OWs1yIAD",
    "email": "abc@email.com",
    "firstName": "Daisy",
    "lastName": "Deeds"
  },
  "canReceivePartnerPromotions": true,
  "canReceivePromotions": true,
  "enrollmentChannel": "Email",
  "enrollmentDate": "2023-06-01",
  "groupCreatedByMember": null,
  "groupName": null,
  "lastActivityDate": null,
  "loyaltyProgramMemberId": "0lMDn000001qkTHMAY",
  "loyaltyProgramName": "NTO Insider",
  "memberCurrencies": [
    {
      "additionalLoyaltyMemberCurrencyFields": {},
      "escrowPointsBalance": 0,
      "expirablePoints": 0,
      "lastAccrualProcessedDate": "2023-06-05T14:21:42.000Z",
      "lastEscrowProcessedDate": null,
      "lastExpirationProcessRunDate": null,
      "lastPointsAggregationDate": null,
      "lastPointsResetDate": null,
      "loyaltyMemberCurrencyName": "NQP Currency test",
      "loyaltyProgramCurrencyId": "0lcDn0000000JUBIA2",
      "loyaltyProgramCurrencyName": null,
      "memberCurrencyId": "0lzDn000003H3VOIA0",
      "nextQualifyingPointsResetDate": null,
      "pointsBalance": 50,
      "qualifyingPointsBalanceBeforeReset": 0,
      "totalEscrowPointsAccrued": 0,
      "totalEscrowRolloverPoints": 0,
      "totalPointsAccrued": 50,
      "totalPointsExpired": 0,
      "totalPointsRedeemed": 0
    },
    {
      "additionalLoyaltyMemberCurrencyFields": {},
      "escrowPointsBalance": 0,
      "expirablePoints": 0,
      "lastAccrualProcessedDate": null,
      "lastEscrowProcessedDate": null,
      "lastExpirationProcessRunDate": null,
      "lastPointsAggregationDate": null,
      "lastPointsResetDate": null,
      "loyaltyMemberCurrencyName": "QP Currency",
      "loyaltyProgramCurrencyId": "0lcDn0000000JUCIA2",
      "loyaltyProgramCurrencyName": null,
      "memberCurrencyId": "0lzDn000003H3VPIA0",
      "nextQualifyingPointsResetDate": "2024-03-15",
      "pointsBalance": 0,
      "qualifyingPointsBalanceBeforeReset": 0,
      "totalEscrowPointsAccrued": 0,
      "totalEscrowRolloverPoints": 0,
      "totalPointsAccrued": 0,
      "totalPointsExpired": 0,
      "totalPointsRedeemed": 0
    }
  ],
  "memberStatus": "Active",
  "memberTiers": [
    {
      "additionalLoyaltyMemberTierFields": {},
      "areTierBenefitsAssigned": false,
      "loyaltyMemberTierId": "0lyDn000001yfVBIAY",
      "loyaltyMemberTierName": "Gold",
      "tierChangeReason": null,
      "tierChangeReasonType": null,
      "tierEffectiveDate": "2023-06-01",
      "tierExpirationDate": null,
      "tierGroupId": "0ltDn0000000JiWIAU",
      "tierGroupName": null,
      "tierId": "0lgDn0000000JY8IAM",
      "tierSequenceNumber": 1
    }
  ],
  "memberType": "Individual",
  "membershipEndDate": "2024-01-01",
  "membershipLastRenewalDate": null,
  "membershipNumber": "Member111459889",
  "referredBy": null,
  "relatedCorporateMembershipNumber": null,
  "transactionJournalStatementFrequency": "Monthly",
  "transactionJournalStatementLastGeneratedDate": null,
  "transactionJournalStatementMethod": "Mail"
}

Retrieve Voucher Details

Retrieves voucher details based on the voucherStatus, productId, productName, productCategoryId, and productCategoryName properties. If there’s no search query parameter, this API retrieves all the vouchers.

GET /members/{membershipNumber}/vouchers

Request

URI Parameters

membershipNumber

String Required

Unique identifier of the member whose vouchers are being retrieved.

Query Parameters

voucherStatus

String

Specifies the status of the voucher.

productId

String

The ID of the product associated with the voucher definition.

productName

String

The type of voucher issued to the member.

productCategoryId

String

The ID of product category associated with the voucher definition.

productCategoryName

String

The name of the product category associated with the voucher definition.

pageNumber

String

The page number to be returned. If you don’t specify a value, the first page is returned. Each page contains 200 vouchers, sorted by their date of creation.

Headers

Authorization

String [Required]

Access token, which is used to make requests to secure resources.

Response

voucher-details-response:

{
  "voucherCount": 3,
  "vouchers": [
    {
      "effectiveDate": "2023-06-12",
      "expirationDate": "2023-09-12",
      "faceValue": 200,
      "isVoucherDefinitionActive": true,
      "isVoucherPartiallyRedeemable": false,
      "status": "Issued",
      "type": "FixedValue",
      "voucherCode": "TestFixed",
      "voucherDefinition": "Fixed OneTimeUse Vouchers",
      "voucherId": "0kDDn0000022pHOMAY",
      "voucherNumber": "00000026"
    },
    {
      "discountPercent": 20,
      "effectiveDate": "2023-06-12",
      "expirationDate": "2023-09-12",
      "isVoucherDefinitionActive": true,
      "isVoucherPartiallyRedeemable": false,
      "productId": "01tDn000004z9R7IAI",
      "productName": "Checked Silk Tie",
      "status": "Issued",
      "type": "DiscountPercentage",
      "voucherCode": "TestDiscount",
      "voucherDefinition": "DiscountProductVouchers",
      "voucherId": "0kDDn0000022pHPMAY",
      "voucherNumber": "00000028"
    },
    {
      "effectiveDate": "2023-06-12",
      "expirationDate": "2023-09-12",
      "faceValue": 200,
      "isVoucherDefinitionActive": true,
      "isVoucherPartiallyRedeemable": false,
      "status": "Issued",
      "type": "FixedValue",
      "voucherCode": "TestPartial",
      "voucherDefinition": "Partial Redeemable Voucher Definiton",
      "voucherId": "0kDDn0000022pHTMAY",
      "voucherNumber": "00000027"
    }
  ]
}

Create Orders

Creates accrual and redemption orders

POST /orders

Request

Headers

Authorization

String [Required]

Access token, which is used to make requests to secure resources.

Body

Media type: application/json

orders-request:

{
  "requestType": "placeOrder",
  "newExternalTransactionNumber": "8888",
  "isOrderFinalCancellation": true,
  "currencyName": "Reward Points",
  "redemptionJournalId": "",
  "order": {
    "loyaltyProgramName": "NTO Insider",
    "membershipNumber": "deh9GiaYSgvBcX1YT30UJMOb7L",
    "id": 1073459966,
    "admin_graphql_api_id": "gid://shopify/Order/1073459966",
    "app_id": 755357713,
    "browser_ip": null,
    "buyer_accepts_marketing": false,
    "cancel_reason": null,
    "cancelled_at": null,
    "cart_token": null,
    "checkout_id": null,
    "checkout_token": null,
    "client_details": null,
    "closed_at": null,
    "confirmed": true,
    "contact_email": null,
    "created_at": "2023-04-24T14:19:30-04:00",
    "currency": "EUR",
    "pointsRedemption": {
      "points": 30,
      "additionalNotes": "Testing",
      "programCurrencyName": "Reward Points"
    },
    "current_subtotal_price": "224.97",
    "current_subtotal_price_set": {
      "shop_money": {
        "amount": "224.97",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "224.97",
        "currency_code": "EUR"
      }
    },
    "current_total_additional_fees_set": null,
    "current_total_discounts": "0.00",
    "current_total_discounts_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "EUR"
      }
    },
    "current_total_duties_set": null,
    "current_total_price": "238.47",
    "current_total_price_set": {
      "shop_money": {
        "amount": "238.47",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "238.47",
        "currency_code": "EUR"
      }
    },
    "current_total_tax": "13.50",
    "current_total_tax_set": {
      "shop_money": {
        "amount": "13.50",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "13.50",
        "currency_code": "EUR"
      }
    },
    "customer_locale": null,
    "device_id": null,
    "discount_codes": [
      {
        "voucherCode": "one20",
        "redeemAmount": 20
      }
    ],
    "email": "",
    "estimated_taxes": false,
    "financial_status": "paid",
    "fulfillment_status": null,
    "landing_site": null,
    "landing_site_ref": null,
    "location_id": null,
    "merchant_of_record_app_id": null,
    "name": "#1002",
    "note": null,
    "note_attributes": [],
    "number": 2,
    "order_number": 1002,
    "order_status_url": "https://jsmith.myshopify.com/548380009/orders/f20dce2f40beaba28ec8c091f94876ce/authenticate?key=07bb8a7c94be78901e2938cfb217ebbd",
    "original_total_additional_fees_set": null,
    "original_total_duties_set": null,
    "payment_gateway_names": [],
    "phone": null,
    "presentment_currency": "EUR",
    "processed_at": "2023-04-24T14:19:30-04:00",
    "reference": null,
    "referring_site": null,
    "source_identifier": null,
    "source_name": "755357713",
    "source_url": null,
    "subtotal_price": "224.97",
    "subtotal_price_set": {
      "shop_money": {
        "amount": "224.97",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "224.97",
        "currency_code": "EUR"
      }
    },
    "tags": "",
    "tax_lines": [
      {
        "price": "13.50",
        "rate": 0.06,
        "title": "State tax",
        "price_set": {
          "shop_money": {
            "amount": "13.50",
            "currency_code": "EUR"
          },
          "presentment_money": {
            "amount": "13.50",
            "currency_code": "EUR"
          }
        },
        "channel_liable": null
      }
    ],
    "taxes_included": false,
    "test": false,
    "token": "f20dce2f40beaba28ec8c091f94876ce",
    "total_discounts": "0.00",
    "total_discounts_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "EUR"
      }
    },
    "total_line_items_price": "224.97",
    "total_line_items_price_set": {
      "shop_money": {
        "amount": "224.97",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "224.97",
        "currency_code": "EUR"
      }
    },
    "total_outstanding": "0.00",
    "total_price": "238.47",
    "total_price_set": {
      "shop_money": {
        "amount": "238.47",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "238.47",
        "currency_code": "EUR"
      }
    },
    "total_shipping_price_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "EUR"
      }
    },
    "total_tax": "13.50",
    "total_tax_set": {
      "shop_money": {
        "amount": "13.50",
        "currency_code": "EUR"
      },
      "presentment_money": {
        "amount": "13.50",
        "currency_code": "EUR"
      }
    },
    "total_tip_received": "0.00",
    "total_weight": 0,
    "updated_at": "2023-04-24T14:19:30-04:00",
    "user_id": null,
    "billing_address": null,
    "customer": null,
    "discount_applications": [],
    "fulfillments": [],
    "line_items": [
      {
        "id": 1071823176,
        "admin_graphql_api_id": "gid://shopify/LineItem/1071823176",
        "productCode": "GC1060",
        "fulfillable_quantity": 3,
        "fulfillment_service": "manual",
        "fulfillment_status": null,
        "gift_card": false,
        "grams": 1300,
        "name": "Modern Striped Dress Shirt",
        "price": "74.99",
        "price_set": {
          "shop_money": {
            "amount": "74.99",
            "currency_code": "EUR"
          },
          "presentment_money": {
            "amount": "74.99",
            "currency_code": "EUR"
          }
        },
        "product_exists": false,
        "product_id": null,
        "properties": [],
        "quantity": 3,
        "requires_shipping": true,
        "sku": null,
        "taxable": true,
        "title": "Big Brown Bear Boots",
        "total_discount": "0.00",
        "total_discount_set": {
          "shop_money": {
            "amount": "0.00",
            "currency_code": "EUR"
          },
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "EUR"
          }
        },
        "variant_id": null,
        "variant_inventory_management": null,
        "variant_title": null,
        "vendor": null,
        "tax_lines": [
          {
            "channel_liable": null,
            "price": "13.50",
            "price_set": {
              "shop_money": {
                "amount": "13.50",
                "currency_code": "EUR"
              },
              "presentment_money": {
                "amount": "13.50",
                "currency_code": "EUR"
              }
            },
            "rate": 0.06,
            "title": "State tax"
          }
        ],
        "duties": [],
        "discount_allocations": []
      }
    ],
    "payment_terms": null,
    "refunds": [],
    "shipping_address": null,
    "shipping_lines": []
  }
}

Response:

create-orders-response:

{
  "correlationId": "4b15eb3a-a0ea-4ba2-9ba7-06e37d25b2a3",
  "message": "Order acknowledged successfully"
}